Skip to content

feat(platform): Xbox GDK feasibility PoC - #658

Merged
aram-devdocs merged 4 commits into
mainfrom
codex/issue-334-xbox-gdk-poc
Apr 2, 2026
Merged

feat(platform): Xbox GDK feasibility PoC#658
aram-devdocs merged 4 commits into
mainfrom
codex/issue-334-xbox-gdk-poc

Conversation

@aram-devdocs

@aram-devdocs aram-devdocs commented Apr 2, 2026

Copy link
Copy Markdown
Owner

Overview

Type: feature

Summary:
Add Xbox GDK feasibility PoC infrastructure behind the xbox-gdk feature flag. Validates the engine's console porting approach using wgpu's DX12 backend with a custom platform backend and raw window handle wrapper. Includes a findings report documenting feasibility, blocking issues, and next steps.

Related Issues: Closes #334

Changes Made

Engine Core (goud_engine/src/)

  • Added xbox-gdk feature flag depending on wgpu-backend
  • Extended WindowBackendKind enum with XboxGdk variant (behind #[cfg(feature = "xbox-gdk")])
  • Extended validate_native_backend_pair to accept (XboxGdk, Wgpu) pair
  • Extended detect_best_backend with target_env = "msvc" guard for Xbox auto-detection
  • Expanded cfg gates across native_backend/ submodules to include xbox-gdk as alternative to native + wgpu-backend
  • New XboxGdkPlatform implementing PlatformBackend trait (stub constructors return BackendNotSupported pending GDK SDK)
  • New XboxWindowHandle with raw-window-handle traits for wgpu DX12 surface creation
  • New WgpuBackend::new_from_raw_handle() forcing DX12 backend for Xbox

FFI Layer (goud_engine/src/ffi/)

No changes

C# SDK (sdks/csharp/)

No changes

Python SDK (sdks/python/)

No changes

TypeScript SDK (sdks/typescript/)

No changes

Codegen Pipeline (codegen/)

No changes

Proc Macros (goud_engine_macros/)

No changes

Tools (tools/)

No changes

WASM (goud_engine/src/wasm/)

No changes

Examples (examples/)

No changes

Documentation

  • New findings report at docs/findings/xbox-gdk-poc.md covering feasibility assessment, blocking issues (DX12 linking, audio, input, shader signing), and recommended next steps

Architectural Compliance

  • Rust-first: All logic lives in Rust; SDKs are thin wrappers
  • FFI boundary: No new FFI exports (internal engine code only)
  • Dependency flow: Imports follow layer hierarchy (Layer 2 only imports from Layer 1 and Layer 2)
  • SDK parity: N/A (no new FFI surface)
  • Unsafe discipline: All unsafe blocks have // SAFETY: comments
  • File size: No file exceeds 500 lines

Testing

  • cargo test passes (4722 tests, 0 failures)
  • cargo clippy -- -D warnings is clean
  • cargo clippy --features xbox-gdk -- -D warnings is clean
  • cargo fmt --all -- --check passes
  • cargo check --features xbox-gdk passes
  • cargo check (default features) unaffected
  • Python SDK tests pass — N/A (no SDK changes)
  • C# SDK tests pass — N/A (no SDK changes)
  • TypeScript SDK tests pass — N/A (no SDK changes)
  • Codegen produces consistent output — N/A (no codegen changes)
  • Pre-commit hooks pass

Code Quality

  • No todo!() or unimplemented!() in production code
  • No #[allow(unused)] without justification comment
  • Error handling uses Result, not unwrap()/expect() in library code
  • Public items have doc comments

Documentation

  • Updated relevant AGENTS.md files — N/A
  • Updated README.md — N/A
  • Added or updated doc comments on new public APIs

Breaking Changes

None

  • API changes: None
  • FFI signature changes: None
  • SDK interface changes: None

Version Bump

Bump type: none
Justification: Feature-gated PoC code, no public API surface change

Security

  • New unsafe blocks each have a // SAFETY: comment and are necessary
  • No new FFI pointer parameters without null checks
  • No new dependencies with known advisories
  • No secrets or credentials in committed files

Performance

N/A — Feature-gated PoC code behind xbox-gdk flag, not active in standard builds.

Deployment

  • NuGet package version updated — N/A
  • Python package version updated — N/A
  • npm package version updated — N/A
  • Native library builds on all targets (macOS verified; Xbox requires GDK SDK)

Reviewer Notes

  • The new_xbox_async function in init.rs intentionally duplicates new_async for the PoC to avoid refactoring the existing init path. A TODO(xbox-gdk) comment marks this for extraction before promotion.
  • On non-MSVC targets, XboxGdkPlatform::new() always returns BackendNotSupported, allowing full type-checking on macOS/Linux.
  • The findings report at docs/findings/xbox-gdk-poc.md identifies 6 blocking issues with severity ratings, the most critical being wgpu's d3d12.dll vs Xbox's d3d12_xs.dll linking gap.
  • Acceptance criterion 2 ("blank window displayed") is not achievable without GDK SDK access; the findings report documents this as a known constraint.

aram-devdocs and others added 3 commits April 2, 2026 14:47
@aram-devdocs @claude
feat(platform): add Xbox GDK feasibility PoC behind feature flag
d9c711a 
Add `xbox-gdk` feature flag and PoC infrastructure for Xbox GDK console
support. This validates the engine's console porting approach using wgpu's
DX12 backend with a custom platform backend.

Changes:
- New `xbox-gdk` Cargo feature (depends on wgpu-backend)
- `XboxGdkPlatform` implementing `PlatformBackend` trait
- `XboxWindowHandle` with raw-window-handle traits for wgpu DX12 surface
- `WgpuBackend::new_from_raw_handle()` forcing DX12 backend
- `WindowBackendKind::XboxGdk` variant and runtime pair validation
- Expanded cfg gates to include xbox-gdk alongside native+wgpu-backend
- Findings report documenting feasibility, blocking issues, and next steps

On non-MSVC targets the platform constructor returns BackendNotSupported,
allowing the full type system to be validated during cross-platform dev.

Closes #334

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@aram-devdocs @claude
fix(platform): guard Xbox auto-detect with target_env=msvc
879d21b 
Prevent detect_best_backend from returning XboxGdk on non-MSVC hosts
when both xbox-gdk and desktop-native features are enabled.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@aram-devdocs @claude
fix(platform): address review feedback for Xbox GDK PoC
bc1170b 
- Add #[allow(dead_code)] to XboxGdkPlatform struct and window_handle()
- Add constructor test for non-MSVC BackendNotSupported error path
- Narrow xbox_surface module visibility to pub(crate)
- Add TODO(xbox-gdk) comment noting shared init refactor needed

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@claude

claude Bot commented Apr 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Claude finished @aram-devdocs's task in 2m 6s —— View job

PR Review: feat(platform): Xbox GDK feasibility PoC

Tasks:

  • Gather context (CLAUDE.md, PR description, changed files)
  • Phase 1: Context gathering and layer identification
  • Phase 2: Architecture validation
  • Phase 3: Anti-pattern scan (FFI safety, unsafe blocks)
  • Phase 4: Quality assessment
  • Phase 5: Security review
  • Phase 6: Scope verification
  • Phase 7: Final review output

Verdict: APPROVED with warnings

The PoC is well-structured, properly feature-gated, and safe to merge. The architecture validates cleanly against the 5-layer model. No blockers.

Phase 1 — Context

  • Layers touched: Layer 2 only (libs/graphics/backend/, libs/platform/)
  • Type: Feature (PoC behind xbox-gdk feature flag)
  • FFI/SDK: No changes — correct for a console platform layer

Phase 2 — Architecture Validation

✅ Dependency flow is downward only. All new code lives in Layer 2 (libs/), importing from Layer 1 (core/) only.
✅ No raw GPU calls outside backend/ module.
✅ xbox-gdk feature depends on wgpu-backend per Cargo.toml — correct dependency chaining.
✅ detect_best_backend uses target_env = "msvc" guard so Xbox doesn't auto-activate on standard Windows desktop builds.
⚠️ init.rs is now 613 lines (limit: 500). The PR checklist incorrectly marks this ✅. See warnings table.

Phase 3 — Anti-Pattern Scan

✅ No todo!() / unimplemented!() in production paths — only // TODO(xbox-gdk): comments.
✅ No unwrap()/expect() in library code — NonZeroIsize::new().ok_or(...) is used correctly.
✅ No FFI exports added — trait-only integration. SDK parity N/A.
⚠️ Significant code duplication between new_async and new_xbox_async (see warnings).

Phase 4 — Quality Assessment

Positive patterns:

  • BackendNotSupported returned on non-MSVC at construction time — clean cross-platform compile story
  • #[allow(dead_code)] on XboxGdkPlatform fields and window_handle() both have justification comments — acceptable for PoC
  • XboxWindowHandle::dummy() failing gracefully with HandleError::Unavailable (via NonZeroIsize null check) is the right design
  • Feature-gated test coverage for all testable error paths

Concerns noted in warnings below.

Phase 5 — Security Review

✅ All unsafe blocks have // SAFETY: comments.
✅ from_raw_hwnd is unsafe fn — correct, the caller takes responsibility.
✅ unsafe impl Send/Sync for XboxWindowHandle are justified — HWND is a copyable integer handle only read during init.
✅ Null HWND is caught by NonZeroIsize::new() before it reaches wgpu, avoiding undefined behavior.
✅ dummy() is only available on non-MSVC builds, preventing accidental use.

Phase 6 — Scope Verification

✅ Changes match PR description precisely.
✅ No unrelated changes.
✅ No version bump needed — no public API surface change.

BLOCKERS

# File Issue
— — None

WARNINGS

# File Issue
W1 wgpu_backend/init.rs (613 lines) Exceeds the 500-line file limit from CLAUDE.md. The PR checklist incorrectly marks this ✅. new_xbox_async (~250 lines) is a near-copy of new_async. The TODO comment is good, but this should be extracted before promotion to production. Fix this →
W2 xbox_gdk_platform.rs:72-116 XboxGdkPlatform implements the full PlatformBackend trait with bodies (poll_events delta time, request_size, etc.) that can never be reached in any current code path, since new() always returns Err. This is intentional for a PoC, but it means the implementations are unvalidated dead code until the GDK SDK is linked. Document this explicitly or gate the impl behind a #[cfg] comment.
W3 native_resources.rs (510 lines) Borderline at 510 lines — just over the 500-line limit. No new additions in this PR pushed it there, but worth noting for the next pass.
W4 docs/findings/xbox-gdk-poc.md The findings/ directory is not registered in src/SUMMARY.md. The findings report won't appear in the built mdBook. If discoverability matters, add a link from src/SUMMARY.md or move to docs/src/development/.

Positive Callouts

  • Feature flag isolation is thorough: every cfg gate in native_backend/ correctly uses any(all(feature = "native", feature = "wgpu-backend"), feature = "xbox-gdk") — no leakage into standard builds.
  • target_env = "msvc" guard on auto-detect (native_runtime.rs:32) prevents Xbox from accidentally being selected on standard Windows desktop CI.
  • NonZeroIsize null guard in xbox_surface.rs:54 cleanly converts the unsafe HWND to a safe HandleError::Unavailable if null — exactly the right approach.
  • Findings report is high quality: severity ratings, mitigation options, and concrete next steps (including the d3d12.dll vs d3d12_xs.dll linking gap which is the real blocker for runtime testing).
  • Test coverage for all reachable paths on non-MSVC: new_returns_backend_not_supported_on_non_msvc and dummy_handle_returns_unavailable both validate the correct failure modes.

@aram-devdocs @claude
fix(ci): split Xbox init and reduce native_resources line count
5f2dd16 
- Extract Xbox wgpu init into dedicated xbox_init.rs (init.rs: 613→336)
- Add dispatch! macro to native_resources.rs (510→228 lines)
- Regenerate ARCHITECTURE.md with xbox-gdk feature flag

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added size/XL and removed size/XL labels Apr 2, 2026
@aram-devdocs
aram-devdocs merged commit 71d477b into main Apr 2, 2026
45 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

size/XL

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

F20-04: Xbox GDK feasibility PoC

1 participant

@aram-devdocs